sandbox: dynamic directory mount & snapshot in go + adds detach #246

thomasjpfan · 2026-01-26T22:47:34Z

This PR cherry picks files from the following PRs to just implement the dynamic directory mounts for Go:

This includes the task command router. I think this is a smaller change and does not impact any public API around sb.exec. Once we have this in, then #242 is easier to review.

cursor · 2026-01-26T22:47:40Z

PR Summary

Medium Risk
Introduces a new sandbox lifecycle contract (Detach) and changes the Sandbox.Terminate signature, plus adds a new gRPC command-router client with custom retry/auth refresh logic; mistakes here could cause resource leaks or break sandbox interactions.

Overview
Adds a new Sandbox.Detach() lifecycle step in Go and makes Sandbox.Terminate(ctx, detach, params) optionally detach after termination; all sandbox operations now fail with a new SandboxDetached error once detached.

Introduces an internal TaskCommandRouterClient (JWT auth + refresh, transient retry) and wires it into Sandbox to support experimental dynamic directory workflows: Sandbox.ExperimentalMountImage(path, image) and Sandbox.ExperimentalSnapshotDirectory(path).

Updates gRPC client connection window sizing, refreshes examples/tests/docs/changelog for the new terminate/detach API, and adds a new sandbox image-mount example plus coverage for detach behavior and mount/snapshot APIs.

^{Written by Cursor Bugbot for commit a07297a. This will update automatically on new commits. Configure here.}

modal-go/sandbox.go

ehdr · 2026-01-27T07:56:33Z

modal-go/task_command_router_client.go

+	"google.golang.org/protobuf/types/known/emptypb"
+)
+
+// tlsCredsNoALPN is a TLS credential that skips ALPN enforcement, implementing


I think this whole thing should no longer be needing after @saltzm fixed something server side, so might work if you just remove it and use the default?

modal-go/task_command_router_client.go

modal-go/sandbox.go

thomasjpfan · 2026-01-27T17:51:01Z

Updated PR with:

Remove the ALPN workaround and verify that taking to the TCR still works
Adds Detach back to both typescript and go

modal-js/src/sandbox.ts

modal-go/config.go

modal-go/task_command_router_client.go

modal-go/examples/sandbox-image-mount/main.go

modal-go/errors.go

modal-go/task_command_router_client.go

modal-go/test/sandbox_test.go

modal-go/test/sandbox_mount_image_test.go

modal-go/sandbox.go

thomasjpfan · 2026-01-27T22:08:33Z

I updated PR:

Disable almost every operation after Detach and added test for this behavior* (Details below)
Removed the JS changes, the PR is already getting too big. I'll open a smaller PR to add Detach to JS.

While implementing this, I made some decisions that are debatable:

Terminate is still allowed after Detach. It feels a little weird to not be able to terminate the sandbox after detach.
- I'm open to changing this.
Terminate does not mark the sandbox as detached, so you can still call sb.Wait after calling Terminate. Terminate will still close the task command routers.
- An alternative is to allow Terminate , Wait and Poll for a detached sandbox and have Terminate mark the sandbox as detached.

modal-go/config.go

saltzm

Everything looks good mod the comment about task_command_router_insecure which isn't being used anymore in the python client

modal-go/examples/sandbox-filesystem-snapshot/main.go

modal-go/examples/sandbox-image-mount/main.go

modal-go/sandbox.go

saltzm · 2026-01-28T19:15:30Z

modal-go/sandbox.go

 func (sb *Sandbox) ensureAttached() error {
 	if sb.detached.Load() {
-		return SandboxDetached{Exception: "Do not call Detach or Terminate until you are done with your sandbox in this session"}
+		return SandboxDetached{Exception: "Do not call Detach until you are done with your sandbox in this session"}


I think I might find this error message confusing if I do like sb.Exec() and get this back - I'll be like "why is it telling me not to call Detach, I'm calling Exec".

I'd expect something more like "Unable to perform operation on a detached sandbox" or "Operations on sandbox after Detach are not allowed" or some such thing

cursor · 2026-01-29T01:40:39Z

modal-go/examples/sandbox-filesystem-snapshot/main.go

 	fmt.Printf("Started Sandbox: %s\n", sb.SandboxID)
 	defer func() {
-		if err := sb.Terminate(context.Background()); err != nil {
+		if err := sb.Terminate(context.Background(), true, nil); err != nil {


Deferred terminate fails after manual detach in examples

Medium Severity

Deferred Terminate calls fail because the target sandbox is already detached. This occurs when a sandbox is explicitly detached or terminated with detach=true before the deferred call executes, leading to a fatal log.

Additional Locations (1)

modal-go/examples/sandbox-volume-ephemeral/main.go#L45-L50

cursor · 2026-01-29T01:40:39Z

modal-go/task_command_router_client.go

+	codes.Canceled:         {},
+	codes.Internal:         {},
+	codes.Unknown:          {},
+}


Duplicated retryable gRPC status codes map

Low Severity

commandRouterRetryableCodes is identical to retryableGrpcStatusCodes defined in client.go (lines 285-291). Both maps contain the exact same five gRPC status codes: DeadlineExceeded, Unavailable, Canceled, Internal, and Unknown. The existing retryableGrpcStatusCodes variable could be reused instead of defining a duplicate.

modal-go/task_command_router_client.go

cursor · 2026-01-29T01:40:39Z

modal-go/sandbox.go

+
+// SandboxTerminateParams are options for Terminate
+type SandboxTerminateParams struct {
+}


Unused parameter and empty params struct

Low Severity

SandboxTerminateParams is an empty struct and the params parameter in Terminate() is never referenced in the function body. The parameter exists but serves no purpose in the current implementation.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-01-29T04:37:57Z

modal-go/task_command_router_client.go

+	closed       atomic.Bool
+
+	refreshJwtGroup singleflight.Group
+}


Exported types only used internally in package

Low Severity

TaskCommandRouterClient struct and TryInitTaskCommandRouterClient function are exported (uppercase names) but are only used within the modal package. These could be unexported to avoid polluting the public API surface.

Additional Locations (1)

modal-go/task_command_router_client.go#L160-L167

thomasjpfan added 2 commits January 26, 2026 17:39

Only image mount

876d3b7

Less changes

2caf2ba

cursor bot reviewed Jan 26, 2026

View reviewed changes

modal-go/sandbox.go Show resolved Hide resolved

ehdr reviewed Jan 27, 2026

View reviewed changes

thomasjpfan added 3 commits January 27, 2026 12:02

Introduce detach back

ffe8c14

Make sure terminate actually calls terminate

1175ead

Remove the need for ALPN workaround

4cb11a9

cursor bot reviewed Jan 27, 2026

View reviewed changes

modal-go/task_command_router_client.go Show resolved Hide resolved

modal-go/sandbox.go Outdated Show resolved Hide resolved

Add docs

a994b38

thomasjpfan changed the title ~~sandbox: dynamic directory mount & snapshot fully - Go~~ sandbox: dynamic directory mount & snapshot in go + adds detach Jan 27, 2026

thomasjpfan added 3 commits January 27, 2026 12:36

Fix lint

0a07097

Simplify tls implemetnation

42a301a

Give terminate error a higher priority

812a561

cursor bot reviewed Jan 27, 2026

View reviewed changes

modal-js/src/sandbox.ts Outdated Show resolved Hide resolved

modal-go/config.go Outdated Show resolved Hide resolved

modal-go/task_command_router_client.go Outdated Show resolved Hide resolved

Make diff smaller

9c89b64

cursor bot reviewed Jan 27, 2026

View reviewed changes

modal-go/examples/sandbox-image-mount/main.go Show resolved Hide resolved

modal-go/errors.go Show resolved Hide resolved

modal-go/task_command_router_client.go Outdated Show resolved Hide resolved

thomasjpfan added 4 commits January 27, 2026 14:13

Less diff

5dc47e5

Ensure that sandbox is attached before running any operation

982ccc2

Less diff

6c3a2a8

Remove ts detach

3eba12d

cursor bot reviewed Jan 27, 2026

View reviewed changes

modal-go/test/sandbox_test.go Outdated Show resolved Hide resolved

modal-go/test/sandbox_mount_image_test.go Outdated Show resolved Hide resolved

Allow for terminate to happen

b37410f

cursor bot reviewed Jan 27, 2026

View reviewed changes

modal-go/sandbox.go Outdated Show resolved Hide resolved

thomasjpfan added 2 commits January 27, 2026 16:49

Use two mutexes

d06531d

Use atomic bool

367125b

saltzm reviewed Jan 28, 2026

View reviewed changes

modal-go/config.go Outdated Show resolved Hide resolved

saltzm reviewed Jan 28, 2026

View reviewed changes

thomasjpfan added 3 commits January 28, 2026 16:55

Remove profile.TaskCommandRouterInsecure

831f1dd

Terminate no longer detaches

7365519

Add detach everywhere

f9c6f6c

cursor bot reviewed Jan 28, 2026

View reviewed changes

modal-go/examples/sandbox-filesystem-snapshot/main.go Outdated Show resolved Hide resolved

modal-go/examples/sandbox-image-mount/main.go Show resolved Hide resolved

thomasjpfan added 3 commits January 28, 2026 19:02

Update examples

10db500

Add changelog

c395951

Add example to readme

e49f593

cursor bot reviewed Jan 28, 2026

View reviewed changes

modal-go/examples/sandbox-image-mount/main.go Outdated Show resolved Hide resolved

modal-go/sandbox.go Show resolved Hide resolved

Add ensureAttached to be extra safe

ec85b2b

saltzm approved these changes Jan 28, 2026

View reviewed changes

thomasjpfan added 6 commits January 28, 2026 19:26

Use a better error message

11b08c3

Add detach and params to Sandbox.Terminate

fb06f43

Update changelog

a4a0084

Fix linter

f08632d

Do not detach

ac9e6f0

Add terminate back in

4c46034

cursor bot reviewed Jan 29, 2026

View reviewed changes

Switch order

a07297a

cursor bot reviewed Jan 29, 2026

View reviewed changes

sandbox: dynamic directory mount & snapshot in go + adds detach #246

Are you sure you want to change the base?

sandbox: dynamic directory mount & snapshot in go + adds detach #246

Uh oh!

Conversation

thomasjpfan commented Jan 26, 2026

Uh oh!

cursor bot commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

Uh oh!

ehdr Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

thomasjpfan commented Jan 27, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thomasjpfan commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

saltzm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

saltzm Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

cursor bot Jan 29, 2026

Choose a reason for hiding this comment

Deferred terminate fails after manual detach in examples

Uh oh!

cursor bot Jan 29, 2026

Choose a reason for hiding this comment

Duplicated retryable gRPC status codes map

Uh oh!

Uh oh!

cursor bot Jan 29, 2026

Choose a reason for hiding this comment

Unused parameter and empty params struct

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Jan 29, 2026

Choose a reason for hiding this comment

Exported types only used internally in package

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cursor bot commented Jan 26, 2026 •

edited

Loading

thomasjpfan commented Jan 27, 2026 •

edited

Loading